Todays professional applications often have picture buttons: buttons that are made from an image as opposed to the standard Macintosh push button, check box or radio button.
Some of the many advantages picture buttons offer are:
√ they can convey more information than a regular button
√ they can convey a message more effectively than regular buttons
√ they can model the real world more effectively
√ they look so darned good!
Tools Plus’ picture buttons are among the best in the industry! Here are some of their features:
◊ transform any icon or PICT into a button
◊ transform a black and white ‘SICN’ icon into a great looking
color 3D button
◊ they are versatile and provide a rich feature set with numerous
behavior and appearance options
◊ they look GREAT on all monitors, even if the button spans
multiple monitors with different settings (i.e., one set to 8-bit
color and the other set to 1-bit monochrome)
◊ they run on all systems
◊ you can create any picture button with a single line of code
◊ it’s like having hundreds of custom CDEFs but a lot easier since
Tools Plus makes it all work
I encourage you to read the User Manual’s chapter on picture buttons since this tutorial is a highly summarized “quick start.”
Button States
~~~~~~~~~~~
Picture buttons, like ordinary buttons, have several states: [1] enabled or disabled, and [2] selected or deselected. The four combinations of these two stages are:
1) enabled not selected
2) enabled selected
3) disabled not selected (optional)
4) disabled selected (optional)
(1) Enabled/deselected: You always need to provide an image (icon or picture) for the enabled, deselected button. Functionally, this image is equivalent to a usable button that is not clicked.
(2) Enabled/selected: The image of a selected button (the functional equivalent of a depressed push button or clicked check box) can either be calculated by Tools Plus, or provided by you in the way of an alternate image. Tools Plus gives you numerous options for the selected button’s appearance if you decide to let Tools Plus calculate the image for you.
(3) Disabled/deselected: The image of a disabled button (the functional equivalent of a dimmed button that is not depressed or clicked) can either be calculated by Tools Plus, or provided by you in the way of an alternate image. Tools Plus gives you numerous options for the disabled button’s appearance if you decide to let Tools Plus calculate the image for you. NOTE: If you decide your button is _never_ disabled (even when its parent window is inactive), you don’t need to create an alternate image for this state.
(4) Disabled/selected: The image of a disabled selected button (the functional equivalent of a dimmed button that is depressed or clicked) can either be calculated by Tools Plus, or provided by you in the way of an alternate image. When calculated by Tools Plus, it takes a combination of the “selected” appearance and “disabled” appearance as specified in numbers 2 and 3. NOTE: If you decide your button is _never_ selected when it is disabled, you don’t need to create an alternate image for this state.
Values and Stages
~~~~~~~~~~~~~~
Picture buttons can optionally have a value associated with them. Like scroll bars, picture buttons can have a minimum, maximum and current value in the range of -32768 to 32767 (a 2-byte integer).
For simple picture buttons, like a click-sensitive icon, you only need a single value, so you might as well specify 0 for the minimum, maximum and current value.
In the Tools Plus demo (not in this tutorial) you can find an example of a button that has a range from -179 to +180, each number representing one degree in a compass. The “globe” picture button in the Tools Plus demo app lets the user click the left side of the button to decrease the value, and the right side to increase the value.
For more elaborate picture buttons such as the “power on/power off” button in this tutorial, a separate image can be displayed for each value the button may have. The power button in this tutorial has a range from 0 (off) to 1 (on) with a unique image for the “off” value and a different image for the “on” value. This is called a multi-stage button.
When buttons have a numeric range, Tools Plus lets you optionally “cycle” the values so that when the current value goes beyond the maximum, it loops back down to the minimum. The same applies for when the value drops below the minimum. The power button in this tutorial increments from 0 to 1, then loops back to 0 again.
Behavior
~~~~~~~
Picture buttons have numerous options that determine how the button behaves. Specifying the behavior your want is as simple as picking and choosing the options you want from a list. Please refer to the User Manual’s Picture Buttons chapter for details on the available options.
The questions you need to ask yourself before designing a picture button are:
(1) Am I using PICT resources or icons for the images?
(2) Do I want an event as soon as the user brings the mouse down
in the button, or wait until the mouse is released?
(3) When the user clicks the button, does it get locked in the
selected state like a radio button (i.e., user must click on
something else to deselect it)
(4) Do I want picture button events to be continuously generated
while the mouse button is down, or get a single event when
the user releases the mouse?
If the button has a range of values…
(5) Should the button’s value change automatically in response to
user action, or should my application change the value?
(6) At what speed should the value change?
(7) Is the button split (left/right or top/bottom) for incrementing/
decrementing the value?
(8) Does the button have multiple stages (separate image for each
value)?
When the button is being selected…
(9) To indicate the button is selected, do I: [i] let Tools Plus darken
the image, [ii] let Tools Plus calculate a color 3D button that
can be either darkened, lightened or pushed, or [iii] supply an
alternate image I’ve created (PICT or icon)?
When the button is being disabled…
(10) To indicate the button is disabled, do I: [i] let Tools Plus lighten
the image, [ii] let Tools Plus calculate a disabled color 3D
button, [iii] supply an alternate image I’ve created (PICT or
icon), or [iv] don’t change the appearance of the button?
Multiple Icons for a Single Image?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tools Plus’ picture buttons display the best possible image based on your monitor’s settings, even if the button crosses several monitors with different settings. The way this is accomplished is that you create several icons for the same image, each icon being dedicated to a specific screen resolution.
The simplest example is a plain black and white ‘ICON’ icon. If that suits your needs, then you don’t need to include any other icons for that image. If you are creating a picture button that is not a perfect 32x32 pixel square, and let’s just say you want to have a color picture button, then you will need to have several icons that all represent a component of the same image. The example below demonstrates this:
ICN# ID = 128: 1-bit B&W icon with mask
icl4 ID = 128: 4-bit color equivalent
icl8 ID = 128: 8-bit color equivalent
In the example above, all the icons represent components of the SAME image (ID = 128). The ICN# supplies the mask that is shared by all the icons as well as the black and white image, the icl4 supplies the color image for monitors set to 4-bits, and the icl8 supplies the color image for monitors set to 8-bit or more. Mind you, you don’t need to create an icl8 if the icl4 is good enough to present on 8-bit (or better) monitors. And if you don’t include the icl4, the black and white equivalent is displayed on monitors set to 4-bits.
An especially interesting icon is the ‘cicn’ because it is a variable size color icon, black and white icon, and mask all combined into a single resource. The only drawback it has is that the same color image is displayed on monitors set to 4-bits or better, and if you do not choose your colors carefully, it may not look very good on a monitor set to 4-bit color. If your application is running on a Macintosh without Color QuickDraw, Tools Plus uses the black and component of the ‘cicn’ ignoring the color information.
Please refer to the User Manual for information on how to number your icon resources for picture buttons.
Warning: If you are using a ‘cicn’ (variable size color) icon that may
be displayed on a Macintosh that doesn’t have Color
QuickDraw, make sure the icon’s size is set to at least 9
pixels wide (although the actual image and mask can be
smaller). A bug in the Macintosh’s ROMs causes a crash
when CopyBits tries to work on a BitMap that is 8 pixels
wide or less.
Multiple PICTs (and lots of them)
~~~~~~~~~~~~~~~~~~~~~~~~~~
Picture resources (‘PICT’s) follow the same thinking as icons except that they introduce some added complexities: (1) there is no such thing as a different kind of PICT based on image depth, and (2) there is no PICT equivalent for a mask.
Tools Plus addresses these issues by letting you use sequentially numbered PICTs as a group of logically related components for the same image. The example below demonstrated this:
PICT ID = 128 Black and white (Base ID)
PICT ID = 129 4-bit
PICT ID = 130 8-bit
PICT ID = 131 Mask (black and white)
The four resources above (not all need to be included) represent a single image for picture button. If you want to provide an alternate image for a selected and/or disabled picture button, each of the four possible states reserves four resource IDs as follows:
(Base ID = 128)
Enabled not Selected ID = 128, 129, 130, 131
Enabled Selected ID = 132, 133, 134, 135
Disabled not Selected ID = 136, 137, 138, 139
Disabled Selected ID = 140, 141, 142, 143
As you can see, up to 16 PICT resources can be used for a single stage button. If you create a multiple stage button, up to 16 PICTs can be used for each of the stages.
NOTE: You do not have to create a PICT for each possible scenario.
You can save work by creating only an 8-bit PICT and have
QuickDraw translate it to the appropriate color depth. If the
button is never selected and disabled, you can omit the four
PICTs related to that combination (i.e., don’t have any PICTs
numbered 140 through 143 in the example above).
Picture Buttons on Color Backgrounds
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your picture button has multiple images (even if it’s just for the deselected and selected states), you need to pay attention to situations where your images have different masks. If this is the case and your picture button is placed on a color background, a white gap will appear in the region where your two masks differ.
You can correct this problem by setting the window’s background color to be the same as the color on which the button is being placed. When the button is created, it remembers the window’s background color and uses it to fill in the gap between mask regions. After the button is created, you can change the window’s background color without concern for existing buttons.
The Event Loop
~~~~~~~~~~~~
The only event you need to be aware of when processing picture buttons is doPictButton (user has selected a picture button). Your application simply responds to the picture button selected by the user.
Tools Plus takes care of the user clicking in the button, as well as refreshing the picture button when required.
